Fixed problem with xcsv derivatives that contained sections in the description.
-
-
-
- <para>FAI/IGC Data File -- Used by the international gliding
+<para>
+FAI/IGC Data File -- Used by the international gliding
community to record gliding flights. IGC files can be converted to
and from tracks representing recorded flights, and routes representing
-task declarations in other formats.</para>
-
+task declarations in other formats.
+</para>
+
+<section id="fmt_igc_notes">
+<title>IGC Data Format Notes</title>
+<para>
+Refer to Appendix 1 of
+<ulink url="http://www.fai.org:81/gliding/gnss/tech_spec_gnss.asp">http://www.fai.org:81/gliding/gnss/tech_spec_gnss.asp</ulink>
+for the specification of the IGC data format.
+</para>
+<para>
+A sample list of software applications that use data in IGC format can be
+found at
+<ulink url="http://www.fai.org:81/gliding/gnss/gnss_analysis_software.pdf">http://www.fai.org:81/gliding/gnss/gnss_analysis_software.pdf</ulink>
+</para>
+<para>
+GPSBabel can be used to translate data in IGC format to and from various other
+formats.
+</para>
+<para>
+Routes in other formats are used to represent IGC task declarations.
+</para>
+<para>
+Tracks in other formats are used to represent IGC recorded flights.
+</para>
+</section>
+
+<section id="fmt_igc_convto">
+<title>Converting to IGC format</title>
+<para>
+IGC files generated by GPSBabel will NOT pass security validation tests since
+the data they contain cannot be proven to originate from an approved flight
+recorder. For most software applications that use IGC files this is not an
+issue but for competition scoring, record and badge claims the generated files
+will not be accepted as proof of a flight.
+</para>
+<para>
+A track stored in another format (GPX for example) representing a recorded
+flight can be converted into an IGC file:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f mytrk.gpx -o igc -F myflight.igc</screen>
+<para>
+If multiple track segments are provided in the input file, the one with the
+most points will be used.
+</para>
+<para>
+A route stored in another format representing a task declaration can be
+converted into an IGC file:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f myrte.gpx -o igc -F mytask.igc</screen>
+<para>
+A route and a track in other formats can be included into a single IGC file:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f mytrk.gpx -f myrte.gpx -o igc -F myflight.igc</screen>
+<para>
+A similar result can be obtained by downloading the track log and routes
+directly from a GPS device connected to a PC. For example to create an IGC
+file from data recorded in a Garmin GPS connected to the first serial port of
+a PC running Linux:
+</para>
+<screen format="linespecific">gpsbabel -t -r -i garmin -f /dev/ttyS0 -o igc -F myflight.igc</screen>
+<para>
+For Windows operating systems:
+</para>
+<screen format="linespecific">gpsbabel -t -r -i garmin -f com1 -o igc -F myflight.igc</screen>
+<para>
+A waypoint file in another format containing a waypoint whose short name is
+"PILOT" can be merged into an IGC file. The description field of the waypoint
+will be used for the pilot name in the IGC file header:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f mytrk.gpx -f myrte.gpx -f mywpt.gpx -o igc -F myflight.igc
+gpsbabel -w -t -r -i garmin -f /dev/ttyS0 -o igc -F myflight.igc</screen>
+<para>
+Some formats such as GPX allow routes, tracks and waypoints to exist in the
+same file and can be used to fully populate an IGC file:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f myall.gpx -o igc -F myflight.igc</screen>
+</section>
+
+<section id="fmt_igc_convfrom">
+<title>Converting from IGC format</title>
+<para>
+Data in an IGC file can be converted into other formats. For example to
+generate OziExplorer files containing tracks representing the recorded
+flight (myozi.plt) and routes representing declared tasks (myozi.rte):
+</para>
+<screen format="linespecific">gpsbabel -i igc -f myflight.igc -o ozi -F myozi</screen>
+<para>
+Or to GPX format:
+</para>
+<screen format="linespecific">gpsbabel -i igc -f myflight.igc -o gpx -F myflight.gpx</screen>
+<para>
+Header information from the IGC file will be written to the description field
+of the track(s).
+</para>
+<para>
+If both pressure altitude and GNSS altitude are recorded in the IGC file, two
+tracks will be written to the new track file, representing the two altitude
+tracks. The latitude, longitude and timestamps in the tracks will be identical.
+</para>
+</section>
+
+<section id="fmt_igc_merge">
+<title>Merging into IGC format</title>
+<para>
+A route stored in another format can be merged with an existing IGC file that
+has no task declaration, to generate a new IGC file with a task declaration:
+</para>
+<screen format="linespecific">gpsbabel -i igc -f myflight.igc -i gpx -f myrte.gpx -o igc -F mynew.igc</screen>
+<para>
+A two dimensional (lat/lon) track recorded during a flight by a GPS receiver
+can be merged with a one dimensional (altitude) track recorded during the same
+flight by a barograph instrument. The result is a three dimensional IGC file
+representing the flight:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f baro.gpx -i igc -f my2D.igc -o igc -F my3D.igc</screen>
+<para>
+The same can be acheived by downloading directly from a barograph instrument
+supported by GPSBabel. For example with a Brauniger IQ Comp GPS variometer:
+</para>
+<screen format="linespecific">gpsbabel -i baroiq -f /dev/ttyS0 -i igc -f my2D.igc -o igc,timeadj=auto -F my3D.igc</screen>
+<para>
+or:
+</para>
+<screen format="linespecific">gpsbabel -i baroiq -f com1 -i igc -f my2D.igc -o igc,timeadj=auto -F my3D.igc</screen>
+<para>
+(Documentation contributed by Chris Jones, Aug 2004)
+</para>
+</section>
+
-
-
-
- <para>Magellan NAV Companion for Palm/OS is not really designed
+<para>
+Magellan NAV Companion for Palm/OS is not really designed
for this sort of use, but its file format is supported and with a
little bit of patience you can both read and write NAV Companion
-waypoints. Please read README.magnav for further tips on getting
-waypoints in and out of NAV Companion. This conversion is based on
+waypoints. This conversion is based on
partially incomplete reverse-engineering of the record format, so it
may not work with all versions of NAV Companion. It has been tested
-with version 2.10 and 3.20.</para>
-
+with version 2.10 and 3.20.
+</para>
+<para>
+Translating NAV Companion waypoints to another format is as easy
+as with any other format. Just find the Companion_Waypoints database
+in your palm backup directory and use it as the input file.
+</para>
+<para>
+When translating waypoints back to NAV Companion, though, you need
+to jump through some hoops:
+</para>
+<para>
+First, you must merge any waypoints that already exist in the database
+in your Palm Backup directory with the ones you are adding; failure to
+do so will result in only the new points being available in NAV Companion,
+even if you give the new database a different name (it will overwrite
+the old database, even in your backup directory. That's a feature of
+PalmOS, not of NAV Companion.)
+</para>
+<para>
+To merge the databases, use a command line like the following:
+</para>
+<screen format="linespecific">gpsbabel -i magnav -f Companion_Waypoints.PDB -i geo -f geocaching.loc -o magnav -F merged.pdb</screen>
+<para>
+Second, you must use the installer to install your new PDB file. Don't
+make the mistake of copying it over the existing Companion_Waypoints.PDB
+file; the one on the handheld will overwrite it rather than merging with
+it.
+</para>
+<para>
+Finally, because NAV Companion is not designed to work with desktop
+applications, you must tell NAV Companion that its waypoints database
+has changed out from under it. One way to do this is to go to the
+waypoints screen and attempt to scroll; that will force it to reread
+the database and fix the record pointers that it keeps on the heap.
+</para>
+
+<para>
+Mapconverter is a format that is read by Mapopolis.com's
+mapconverter application.
+</para>
+<para>
+Mapconverter is an application used to create userland maps and map data for
+Mapopolis.com's Mapopolis program. The mapconverter format is essentially
+waypoint data prepared in a format that the mapconverter application will
+accept.
+</para>
+<para>
+The steps for using GPSBabel and Mapconverter go something like this:
+</para>
+<para>
+Step 1: Create a mapconverter file using gpsbabel.
+</para>
+<screen format="linespecific">gpsbabel -i geo -f geocaching.loc -o mapconverter -F foo.txt</screen>
+<para>
+Step 2: Launch mapconverter.exe and choose foo.txt as your input file.
+ Click the begin button to have mapconverter process foo.txt.
+</para>
+<para>
+If all goes successfully, you should have a file called "foo.pdb" ready
+for syncing with your PDA. Put it wherever Mapopolis thinks it should be
+on your PDA.
+</para>
+<section id="fmt_mapconverter_notes">
+<title>Notes</title>
+<itemizedlist>
+<listitem>
+<para>
+GPSBabel will write the name of its own output file in the output file
+ it creates as the input for Mapconverter. Mapconverter will replace
+ the extension of this filename with ".pdb".
+</para>
+</listitem>
+<listitem>
+<para>
+The PocketPC version of Mapopolis doesn't notice files with the ".pdb"
+ extension. To make this work, change the extension to ".mlp" when
+ copying the mapconverter output to your PocketPC PDA.
+</para>
+</listitem>
+<listitem>
+<para>
+Mapconverter only works with Mapopolis version 3.x. Mapopolis version
+ 4 will refuse to load mapconverter maps. There is no known work-around
+ for this at the time of this writing.
+</para>
+</listitem>
+<listitem>
+<para>
+Mapconverter is no longer available from the Mapopolis website. If you
+ need a copy of mapconverter, ask on your local GPS Software discussion
+ forum and I'm sure someone will have it. As far as I know, It was never
+ actually acknowledged/supported by Mapopolis to begin with.
+</para>
+</listitem>
+</itemizedlist>
+</section>
-
-
- <para>Mapconverter is a format this is read by Mapopolis.com's
-mapconverter application. Full details of it's usage are available in
-the file README.mapconverter.</para>
-
+<para>
+Sometimes there is a discrepancy between the internal clock in the barograph
+instrument and GPS time which can result in the altitude and ground positions
+not correlating correctly. This can be corrected manually by passing the time
+difference in seconds between the two time domains through the "timeadj"
+parameter. This can be any positive or negative integer:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f baro.gpx -i igc -f my2D.igc -o igc,timeadj=27 -F my3D.igc</screen>
+<para>
+GPSBabel can also attempt to deduce the time difference automatically. This
+is done by comparing the time that it thinks that you landed on the GPS track
+and the barograph and adjusting accordingly:
+</para>
+<screen format="linespecific">gpsbabel -i gpx -f baro.gpx -i igc -f my2D.igc -o igc,timeadj=auto -F my3D.igc</screen>
+
-
-
-
- <para> Microsoft's PocketStreets 2002 Pushpin (.PSP) format is
-not yet completely documented. THE .PSP MODULE DOES NOT WORK WITH MS
-STREETS & TRIPS 2002 .EST FILES. To create .PSP files from
+<para>
+Microsoft's PocketStreets 2002 Pushpin (.PSP) format is
+not yet completely documented. <emphasis>The .PSP module does not work with
+MS Streets & Trips 2002 .EST files</emphasis> To create .PSP files from
Streets & Trips 2002, you will need to have PocketStreets support
installed.
- </para>
- <para>Please note that MS Streets & Trips only *EXPORTS*
+</para>
+<para>
+Please note that MS Streets & Trips only <emphasis>exports</emphasis>
.PSP files. It does not import them. MS Streets & Trips 2002 only
imports CSV files. To use .PSP files, simply copy them over to the
same folder on the mobile device as the map (.MPS), and open
outside of the exported map area, the pin will be "grayed-out" and
unused in PocketStreets. This is a good thing as it allows us to
create one big .PSP file that covers multiple .MPS files.
-Unfortunately, you need one .PSP file for every .MPS file. :(</para>
-
+Unfortunately, you need one .PSP file for every .MPS file.
+</para>
+<section id="fmt_psp_faq">
+<title>Frequently Asked Questions</title>
+<qandaset>
+<qandaentry>
+<question>
+<para>
+Why should I use GPSBabel/psp to make pushpins when Streets & Trips (S&T)
+ already does that for me?
+</para>
+</question>
+<answer>
+<para>
+GPSBabel/psp has the advantage of being able to create pushpins
+<emphasis>without</emphasis>
+ creating the associated map file and the need to "import" the waypoint
+ data into S&T. Through a series of scripts, you can create a dozen
+ or so PSP files in a few seconds as opposed to a few weeks using the
+ S&T interface. The maps are not going to change between sessions,
+ only the pins will. Why waste all that time creating maps when all you
+ really want are updated pins? As an aside, GPSBabel/psp creates points
+ <emphasis>with the proper coordinates</emphasis>
+ where S&T does not in some areas of the U.S.
+ (Nashville, TN for instance).
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+I keep getting a blank (32 byte) PSP file.
+</para>
+</question>
+<answer>
+<para>
+There are either no points to write, or you have botched the command
+ line for GPSBabel. GPSBabel is sensitive to UPPER and lower case
+ on the command line. A simple command line to create PSP files
+ looks like this:
+</para>
+<screen format="linespecific">gpsbabel -i geo -f geocaching.loc -o psp -F NewOrleans.psp</screen>
+<para>
+ Note the use of "-f" for INPUT files and "-F" for OUTPUT files.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+I've created a PSP file, now what do I do with it?
+</para>
+</question>
+<answer>
+<para>
+To use pushpins in Pocketstreets, you need to have both a map and a
+ pushpin file. These two files must exist in the same folder and have
+ exactly the same base name as the map. For example, the pins that
+ correspond to the map "NewOrleans.mps" should be named "NewOrleans.psp".
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+I don't have a map. What do I do now?
+</para>
+</question>
+<answer>
+<para>
+Create one using the "Export map to Pocketstreets" option in S&T. You
+ can also pick up some major city maps on the web from the MS Pocketstreets
+ website if you are interested in seeing how it works.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+I have .EST files, not .PSP files. What's up with that?
+</para>
+</question>
+<answer>
+<para>
+In order to make PSP files, you need to use the "Export map to
+ Pocketstreets" function in S&T. .EST files are for use in S&T, not
+ Pocketstreets.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+ The .PSP files differ when I use GPSBabel/psp versus Pocketstreets to
+ create them. What's up?
+</para>
+</question>
+<answer>
+<para>
+Pocketstreets makes corrections to the S&T waypoint data upon initial
+ loading. GPSBabel/psp writes PSP files with these corrections already made.
+ Ask MS.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+Does GPSBabel/psp work with (Autoroute, Mappoint, etc..) .PSP files?
+</para>
+</question>
+<answer>
+<para>
+As of this writing, I haven't seen any so I can't be sure. If they
+ follow the same layout as S&T 2002, I'd imagine so.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+ Does GPSBabel/psp work with (S&T 2001, S&T 2002, etc...) files?
+</para>
+</question>
+<answer>
+<para>
+MS changed the file layout between S&T 2001 and S&T 2002. The GPSBabel psp
+ module is known to work fine with S&T 2002 and 2003.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+Does GPSBabel/psp work with (insert your country/location here) maps?
+</para>
+</question>
+<answer>
+<para>
+If it doesn't, feel free to inquire on the
+<ulink url="https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc">GPSBabel-Misc</ulink>
+mailing list.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+What do you mean S&T writes points with the wrong coordinates?
+</para>
+</question>
+<answer>
+<para>
+At some point in the "Export map to Pocketstreets" function in S&T,
+ it goofs the lat/long data. Points in Nashville tended to shift
+ 1.4 miles WEST of their original location. I'm not a geometry buff,
+ but I'd imagine they have a reference point for generating coordinates
+ that's wrong in (at least) that area.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+I have 800 waypoints that cover a dozen or so Pocketstreets maps.
+ Do I need to to split my points up into smaller chunks to match the
+ area covered by the maps?
+</para>
+</question>
+<answer>
+<para>
+ No. Pocketstreets will "ignore" points that are outside of the map
+ area. Points that are not on the current map will be "grayed out"
+ in pushpin explorer in Pocketsreets. This is the reason the PSP
+ module was written for GPSBabel in the first place.
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+Where can I find documentation for the layout of PSP files?
+</para>
+</question>
+<answer>
+<para>
+Just about everything I know about the PSP file format is documented
+ in the source. To the best of my knowledge, there is no documentation
+ (and for good reason, I've come to discover).
+</para>
+</answer>
+</qandaentry>
+<qandaentry>
+<question>
+<para>
+I have some other problem, what do I do?
+</para>
+</question>
+<answer>
+<para>
+Ask your question on the <ulink url="https://lists.sourceforge.net/lists/listinfo/gpsbabel-misc">GPSBabel-Misc</ulink> mailing list.
+</para>
+</answer>
+</qandaentry>
+</qandaset>
+</section>
+
-
-
-
- <para>Delorme XMapHandHeld Street Atlas USA is another of the
+<para>
+Delorme XMapHandHeld Street Atlas USA is another of the
billion CSV variants. This is the format used by XmapHH SA USA on (at
-least) PocketPC O/S. Please see README.xmapwpt for more information
-on it's intricacies. This XMap is not to be confused with the XMap
-mentioned above. Contributed to GPSBabel by Alex Mottram.</para>
+least) PocketPC O/S.
+</para>
+<para>
+This XMap is not the same as the simpler
+<link linkend="fmt_xmap">XMap</link> format, which is used with Topo USA 4.0
+and XMapHH for Palm.
+</para>
+<para>
+Delorme XMap Handheld .WPT for PocketPC is a bit of a kludge. This
+chapter covers XMap Handheld Street Atlas USA edition.
+</para>
+<para>
+XMap on the PocketPC stores its waypoints in individual .wpt files.
+For example, waypoints generated by XMap on the PocketPC are stored
+by default in the "My Documents" folder using the sequential names
+"XMap1.wpt", "XMap2.wpt", ad nauseum. Needless to say, this is not very
+efficient.
+</para>
+<para>
+As writing multiple waypoint files is outside of the scope of GPSBabel,
+GPSBabel chooses to write one big file, one waypoint per line.
+Extracting lines from this file is left as an exercise for the end user.
+A simple Perl script to handle this conversion is included at the end
+of this chapter.
+</para>
+<para>
+It should also be noted that <emphasis>reading</emphasis> multiple files
+is indeed possible, but if you have more than a few points, it can be a task.
+For example:
+</para>
+<screen format="linespecific">gpsbabel -i xmapwpt -f Xmap1.wpt -f Xmap2.wpt -o mapsend -F mapsend.wpt</screen>
+<para>
+will read the two Xmap .wpt files and write one mapsend file. This
+is fine for a small handful of points, but could be quite cumbersome
+for folks like me who have 100+ waypoints loaded into XMap. For *nix
+folks, something as simple as:
+</para>
+<screen format="linespecific">cat *.wpt > /tmp/foo.wpt
+gpsbabel -i xmapwpt -f foo.wpt -o mapsend -F mapsend.wpt </screen>
+<para>
+will do the trick just fine.
+</para>
+<programlisting format="linespecific">
+#!/full/path/to/perl
+$INPUTFILE = @ARGV[0];
+$TARGETDIR = @ARGV[1];
+$FILENAME = @ARGV[2];
+
+if (! $FILENAME) {
+ print "Usage: xmap_split.pl INPUT_FILE OUTPUT_DIRECTORY FILENAME_BASE\n";
+ print " (i.e. xmapl_split.pl points.wpt /tmp/points GPSB)\n";
+ print " (created GPSB0001-GPSBXXXX in /tmp/points/ from points.wpt)\n";
+ exit;
+}
+
+open (INFILE, $INPUTFILE) || die "Cannot open $INPUTFILE for read!\n";
+
+while (<INFILE>) {
+ $lc++;
+ $filename = sprintf("%s/Gpsb%04d.wpt", $TARGETDIR, $lc);
+
+ open (OUTFILE, ">$filename") || die "Cannot open $filename for write!\n";
+
+ print OUTFILE $_;
+
+ close(OUTFILE);
+}
+
+exit;
+
+</programlisting>
+
+<para>Contributed to GPSBabel by Alex Mottram.</para>
<title>$line[4] ($line[2])</title>
END
print FILE expandoptions($line[1]);
- include($id,"formats");
$going = 1;
$dooptions = 1;
if ( defined($line[5]) && ($line[5] ne $line[2]) ) {
$dooptions=0;
}
}
+ include($id,"formats");
}
elsif ($going && $dooptions && ($line[0] eq 'option')) {
$nid = 'fmt_'.$id.'_o_'.$line[2];
projects / gpsbabel.git / commitdiff